QA1236 - Debugging Graphics with QuartzDebug

Q: How do I use QuartzDebug to debug graphics issues?

A: QuartzDebug is a debugging interface for the Quartz graphics system with several powerful tools to help you identify a number of graphics display and performance problems. The latest version of Quartz Debug can be downloaded from here.

Note: despite its name, QuartzDebug can also be an effective tool for debugging QuickDraw operations on Mac OS X since ultimately all drawing operations pass through Quartz.

Options Window and Window List

Upon launch, the QuartzDebug options window Figure 1 appears. It contains four debugging checkboxes (all initially deselected) and a Show Window List button.

The "Autoflush drawing" checkbox flushes the contents of a CoreGraphics graphics context after each drawing operation, rather than wait for the CGContextFlush(). This is useful for examining every single drawing operation.

When "Flash screen updates" is selected, regions of the screen that are about to be updated are painted yellow, followed by a brief pause, followed by the actual screen update. This allows you to see screen updates as they occur. The pause allows you to see the region in yellow; without it, the screen would be updated immediately, possibly faster than you can perceive it. To turn off the pause, select the "No delay after flash option."

When "Flash identical updates (red)" is selected, regions of the screen that are about to be updated, but are the same as the content already present in the window backing store, are painted red. The red is followed by a brief pause, followed by the actual screen update. This allows you to see which regions of the window are being drawing redundantly as the content is already present in the window backing store. To turn off the pause, select the "No delay after flash option."

Figure 1. QuartzDebug options window

Use the Show Window List button to display a window containing a static snapshot of the system-wide window list. The list identifies the owner of each window and the memory the window occupies. This is useful for understanding the impact of buffered windows on your application's memory footprint.

Figure 2 shows a sample window list and Table 1 explains the meaning of each column in the window list.

This list is a snapshot, not updated automatically. To update the snapshot, either press the Show Window List button again, or choose Show Window List from the File menu. Note that you will need to scroll the window list window down to see the new snapshot.

Figure 2. QuartzDebug window list

Table 1. QuartzDebug window list columns

Column	Description
CID	The connection ID of the window. Used internally by the window server. Typically, the connection ID is the same for all windows owned by a process.
Application	The name of the application that owns the window.
WID	The ID of the window itself. Used internally by the window server.
kBytes	The amount of memory occupied by the window buffer and other large data structures. Specified in kilobytes. The letter I is appended to the size if the buffer is invalid (in need of an update). The letter C is appended if the window has been automatically been compressed by the window server.
Origin	Screen-relative origin of the window (in pixels).
Size	Size of the window (in pixels).
Type	Buffered windows are buffered in shared memory. All graphics operations are recorded in the backing buffer and drawn to screen by the window server as necessary. Only the portions of a Retained window that are obscured by other windows are saved in the buffer. This results in some memory savings, but disables translucency. Graphics operations in NonRetained windows are not recorded at all.
Encoding	Depth of the window's buffer (the number of bits per pixel). The letters -A are appended if the window buffer has an alpha channel. Note that the window buffer includes the window's title bar and frame (or, in Carbon terms, "structure region").
On Screen	Whether the window is visible and on screen or offscreen and hidden from view.
Shared	Whether the window is shared or not. Shared windows can be manipulated by multiple applications. Non-shared windows are only modifiable by the application specified in the Application column.
Fade	Opacity of the window. Opacity is separate from the window's alpha channel. Ranges from 0% to 100%, where 0% indicates a completely transparent window; 100% indicates a completely opaque window.
Level	The window level. Windows at higher levels can never be placed visually below windows at lower levels. Values from LONG_MIN + 1 to LONG_MAX - 16 are supported.

Tools Menu Options

The Tools menu provides a few other options

The "Show/Hide Frame Meter" menu option displays or hides the performance frame meter as shown in Figure 3. The frame meter displays the number of screen updates per second. It also includes a mini cpu frame meter that displays the cpu usage. It is a transparent window, that can moved around by click-dragging from any part of the window.

Figure 3. Frame Meter

The "Disable/Enable Quartz Extreme" menu option allows you to disable or re-enable Quartz Extreme in the system. See the Quartz Extreme page for more information.

The "Refresh Windows List" refreshes the window list available from the Options Window.

[Mar 27 2002]

Developer Documentation | Technical Notes | Development Kits | Sample Code